A note: the ROS_DISTRO env variable isn't set before you source the setup.bash file, so that would not be in your environment yet to work. This is actually true of several of the changes in this PR.

Do you think that may cause more problems than it solves if when using ROS_DISTRO when not set it will return an empty string? I feel like that might confuse users if they get errors trying to access source /opt/ros//setup.bash or apt install ros--gazebo-ros-pkgs because the variable is not set

I guess you are right, it would definitely make it more confusing.
Furthermore for places like build_docs/index.rst, we seem to source /opt/ros/<distro>/setup.bash, do you think we should suggest users to have setup.bash sourced before running the commands wherever I have mentioned the changes, or do you think there is a better way to handle this, or if it is alright as it is?

For Iron and Older
==================

.. code:: bash

  source /opt/ros/<distro>/setup.bash
  sudo apt install \
    ros-$ROS_DISTRO-navigation2 \
    ros-$ROS_DISTRO-nav2-bringup \
    ros-$ROS_DISTRO-turtlebot3*

For Jazzy and Newer
===================

.. code:: bash

  source /opt/ros/<distro>/setup.bash
  sudo apt install \
    ros-$ROS_DISTRO-navigation2 \
    ros-$ROS_DISTRO-nav2-bringup \
    ros-$ROS_DISTRO-nav2-minimal-tb*

Build
*****

That would help for this case, but I think for all cases where you need to source (at least), then we would need to not use ROS_DISTRO. I think that counts for more than just in the build docs -- it might be worth looking over your changes and see for what other situations we haven't yet told the user to source the setup script and add that too (or leave as-is)